Crate kira

Source
Expand description

§Kira

Kira is a backend-agnostic library to create expressive audio for games. It provides tweens for smoothly adjusting properties of sounds, a flexible mixer for applying effects to audio, a clock system for precisely timing audio events, and spatial audio support.

To get started, create an AudioManager and use it to play a StaticSoundData or StreamingSoundData.

§Examples

Playing a sound multiple times simultaneously:

use kira::{
	manager::{
		AudioManager, AudioManagerSettings,
		backend::DefaultBackend,
	},
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
};

// Create an audio manager. This plays sounds and manages resources.
let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let sound_data = StaticSoundData::from_file("sound.ogg")?;
manager.play(sound_data.clone())?;
// After a couple seconds...
manager.play(sound_data.clone())?;
// Cloning the sound data will not use any extra memory.

Gradually speeding up a sound over time:

use std::time::Duration;

use kira::{
	manager::{
		AudioManager, AudioManagerSettings,
		backend::DefaultBackend,
	},
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
	tween::Tween,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let sound_data = StaticSoundData::from_file("sound.ogg")?;
let mut sound = manager.play(sound_data)?;
// Start smoothly adjusting the playback rate parameter.
sound.set_playback_rate(
	2.0,
	Tween {
		duration: Duration::from_secs(3),
		..Default::default()
	},
);

Playing a sound with a low-pass filter applied (this makes the audio sound muffled):

use kira::{
	manager::{
		AudioManager, AudioManagerSettings,
		backend::DefaultBackend,
	},
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
	track::TrackBuilder,
	effect::filter::FilterBuilder,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
// Create a mixer sub-track with a filter.
let track = manager.add_sub_track({
	let mut builder = TrackBuilder::new();
	builder.add_effect(FilterBuilder::new().cutoff(1000.0));
	builder
})?;
// Play the sound on the track.
let sound_data = StaticSoundData::from_file("sound.ogg")?
	.output_destination(&track);
manager.play(sound_data)?;

Playing sounds in time with a musical beat:

use kira::{
	manager::{
		AudioManager, AudioManagerSettings,
		backend::DefaultBackend,
	},
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
	clock::ClockSpeed,
};

const TEMPO: f64 = 120.0;

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
// Create a clock that ticks 120 times per second. In this case,
// each tick is one musical beat. We can use a tick to represent any
// arbitrary amount of time.
let mut clock = manager.add_clock(ClockSpeed::TicksPerMinute(TEMPO))?;
// Play a sound 2 ticks (beats) from now.
let sound_data_1 = StaticSoundData::from_file("sound1.ogg")?
	.start_time(clock.time() + 2);
manager.play(sound_data_1)?;
// Play a different sound 4 ticks (beats) from now.
let sound_data_2 = StaticSoundData::from_file("sound2.ogg")?
	.start_time(clock.time() + 4);
manager.play(sound_data_2)?;
// Start the clock.
clock.start();

§Features

The Kira crate has the following feature flags:

  • cpal (enabled by default) - enables the cpal backend and makes it the default for audio managers. This allows Kira to talk to the operating system to output audio. Most users should leave this enabled.
  • symphonia (enabled by default) - allows loading and streaming audio from common audio formats, like MP3 and WAV.
    • mp3 (enabled by default) - enables support for loading and streaming MP3 audio (enables the symphonia feature automatically)
    • ogg (enabled by default) - enables support for loading and streaming OGG audio (enables the symphonia feature automatically)
    • flac (enabled by default) - enables support for loading and streaming FLAC audio (enables the symphonia feature automatically)
    • wav (enabled by default) - enables support for loading and streaming WAV audio (enables the symphonia feature automatically)
  • serde - adds Serialize and Deserialize implementations for the following types:
  • assert_no_alloc - uses the assert_no_alloc crate to cause panics if memory is allocated or deallocated on the audio thread. This is mainly useful for people developing Kira itself.
  • android_shared_stdcxx - enables cpal’s oboe-shared-stdcxx which can be helpful for Android compilation

§Loading other audio file formats

Kira will be able to load any audio format that Symphonia supports with its current enabled features. For example, to add support for AAC files, you can add symphonia to your Cargo.toml with the aac feature:

symphonia = { version = "0.5.2", features = ["aac"] }

Kira’s mp3, ogg, flac, and wav feature flags are provided for convenience.

See the symphonia documentation for a list of supported container formats and codecs.

§Performance using the dev profile

By default, Rust programs run with the dev profile are not optimized. This can lead to poor performance of audio playback and long loading times for audio files. You can alleviate this by building Kira and its audio-related dependencies with a higher optimization level. Add the following to your Cargo.toml:

[profile.dev.package.kira]
opt-level = 3

[profile.dev.package.cpal]
opt-level = 3

[profile.dev.package.symphonia]
opt-level = 3

[profile.dev.package.symphonia-bundle-mp3]
opt-level = 3

[profile.dev.package.symphonia-format-ogg]
opt-level = 3

[profile.dev.package.symphonia-codec-vorbis]
opt-level = 3

[profile.dev.package.symphonia-bundle-flac]
opt-level = 3

[profile.dev.package.symphonia-format-wav]
opt-level = 3

[profile.dev.package.symphonia-codec-pcm]
opt-level = 3

You can also build all of your projects with a higher optimization level by using this snippet instead:

[profile.dev.package."*"]
opt-level = 3

Building dependencies with a higher optimization level does increase compile times, but only when compiling your project from scratch. If you only make changes to your crate, you’re not recompiling the dependencies, so you don’t suffer from the longer compilation step in that case. Building dependencies optimized and the main crate unoptimized can be a good balance of performance and compile times for games.

Modules§

  • clock
    Precise timing for audio events.
  • command
    Helpers for sending commands from the gameplay thread to the audio thread. You’ll only need to use this if you’re making your own implementation of Sound, Effect, or Modulator.
  • effect
    Modifies audio signals.
  • manager
    The main entrypoint for controlling audio from gameplay code.
  • modulator
    Global values that parameters (like volume and playback rate) can be linked to.
  • sound
    Sources of audio.
  • spatial
    Positions audio in 3D space.
  • track
    Organizes and applies effects to audio.
  • tween
    Smooth interpolation between values.

Macros§

Structs§

  • Frame
    A stereo audio sample.
  • ResourceLimitReached
    An error that is returned when a resource cannot be added because the maximum capacity for that resource has been reached.

Enums§

Functions§

  • interpolate_frame
    Given a previous frame, a current frame, the two next frames, and a position x from 0.0 to 1.0 between the current frame and next frame, get an approximated frame.